/**
 ******************************************************************************
 * @file    motor_driver.h
 * @brief   TB6612FNG 电机驱动库头文件
 * @author  XiFeng (Adapted for TB6612)
 * @date    2025-07-07
 ******************************************************************************
 * @attention
 *
 * 本库专为TB6612FNG电机驱动芯片设计
 * - 使用1个PWM引脚控制速度
 * - 使用2个GPIO引脚(IN1, IN2)控制方向
 * - STBY引脚需要在外部单独置为高电平来使能芯片
 *
 ******************************************************************************
 */

#ifndef __MOTOR_DRIVER_H__
#define __MOTOR_DRIVER_H__

#ifdef __cplusplus
extern "C" {
#endif

/* Includes ------------------------------------------------------------------*/
#include "main.h"
// 以下头文件如果main.h中已包含，则可以省略
#include "tim.h"
#include "gpio.h"

/* Exported types ------------------------------------------------------------*/

/**
 * @brief 电机状态枚举 (为TB6612增加刹车状态)
 */
typedef enum {
    MOTOR_STATE_STOP = 0,     // 停止 (滑行/Coast)
    MOTOR_STATE_FORWARD,      // 正转
    MOTOR_STATE_BACKWARD,     // 反转
    MOTOR_STATE_BRAKE,        // 刹车 (Brake)  <- 新增状态
    MOTOR_STATE_ERROR         // 错误
} MotorState_t;

/**
 * @brief 电机硬件配置结构体 (适配TB6612)
 */
typedef struct {
    TIM_HandleTypeDef* htim;        // PWM定时器句柄
    uint32_t channel;               // PWM通道
    GPIO_TypeDef* in1_port;         // 方向控制引脚1 端口
    uint16_t in1_pin;               // 方向控制引脚1 引脚
    GPIO_TypeDef* in2_port;         // 方向控制引脚2 端口
    uint16_t in2_pin;               // 方向控制引脚2 引脚
} MotorHW_t;

/**
 * @brief 电机驱动实体结构体
 */
typedef struct {
    MotorHW_t hw;                   // 硬件配置
    int8_t speed;                   // 当前速度 (-100 到 +100)
    MotorState_t state;             // 当前状态
    uint8_t enable;                 // 使能标志
    uint8_t reverse;                // 电机安装方向 (0-正装, 1-反装)
} Motor_t;

/* Exported constants --------------------------------------------------------*/

// 注意：您原来的定义是 +/-1000，但函数注释是 +/-100。
// TB6612的逻辑更适合标准的 +/-100 百分比控制，因此这里统一为100。
#define MOTOR_SPEED_MAX         100      // 最大速度 (正转100%)
#define MOTOR_SPEED_MIN         -100     // 最小速度 (反转100%)

#define MOTOR_PWM_PERIOD        999       // PWM周期 (ARR值), 对应100%占空比
#define MOTOR_MIN_PWM_THRESHOLD 200       // 最小PWM阈值 (电机启动的最低占空比，根据实际情况调整)

/* Exported macros -----------------------------------------------------------*/

/* Exported functions prototypes ---------------------------------------------*/


/**
 * @brief 创建电机实体 (适配TB6612)
 * @param motor: 电机实体指针
 * @param htim: PWM定时器句柄
 * @param channel: PWM通道 (TIM_CHANNEL_1~4)
 * @param in1_port, in1_pin: 方向控制引脚1
 * @param in2_port, in2_pin: 方向控制引脚2
 * @param reverse: 电机安装方向 (0-正装, 1-反装)
 * @retval 0: 成功, -1: 参数错误
 */
int8_t Motor_Create(Motor_t* motor,
                    TIM_HandleTypeDef* htim,
                    uint32_t channel,
                    GPIO_TypeDef* in1_port,
                    uint16_t in1_pin,
                    GPIO_TypeDef* in2_port,
                    uint16_t in2_pin,
                    uint8_t reverse);

/**
 * @brief 设置电机速度
 * @param motor: 电机实体指针
 * @param speed: 速度值 (-100 到 +100)
 * 正数为正转，负数为反转，0为滑行停止
 * @retval 0: 成功, -1: 参数错误
 */
int8_t Motor_SetSpeed(Motor_t* motor, int8_t speed);

/**
 * @brief 停止电机 (滑行模式)
 * @param motor: 电机实体指针
 * @retval 0: 成功, -1: 参数错误
 */
int8_t Motor_Stop(Motor_t* motor);

/**
 * @brief 刹车电机 (快速停止)
 * @param motor: 电机实体指针
 * @retval 0: 成功, -1: 参数错误
 */
int8_t Motor_Brake(Motor_t* motor);


/**
 * @brief 获取电机状态
 * @param motor: 电机实体指针
 * @retval 电机状态
 */
MotorState_t Motor_GetState(Motor_t* motor);

/**
 * @brief 使能/失能电机 (软件层面)
 * @param motor: 电机实体指针
 * @param enable: 1-使能, 0-失能
 * @retval 0: 成功, -1: 参数错误
 */
int8_t Motor_Enable(Motor_t* motor, uint8_t enable);

#ifdef __cplusplus
}
#endif

#endif /* __MOTOR_DRIVER_H__ */

